
package net.frenopatico.kynes.dao;

import java.io.Serializable;
import java.util.List;

import com.google.appengine.api.datastore.Key;

/**
 * Basic CRUD operations for T entities with PK id field.
 * 
 * @author Eduardo Ramírez <edu.kynes@gmail.com>
 *
 * @param <T> type of the entities to persist.
 * @param <PK> type of the T's id field.
 */
public abstract interface GenericDao<T, PK extends Serializable> {

    /**
     * Returns <b>true</b> if an <T> with the given Id exists in the persistance, <b>false</b> otherwise.
     * 
     * @param entityId the entity's Id.
     * @return if a T entity exists with the given id. 
     */
    boolean exists( PK entityId );

    /**
     * Returns an T entity with the given Id.
     * 
     * @param entityId the T's Id.
     * @return the referenced T. 
     */
    T get( PK entityId );

    /**
     * Returns a T entity referenced by the given Key.
     * 
     * @param entityKey the T's id field.
     * @return the referenced T. 
     */
    T getByKey( Key entityKey );

    /**
     * Returns all T entities in the persistance.
     * 
     * @return all T entries.
     */
    List<T> getAll();

    /**
     * Returns all entities of T type, removing duplicated entries.
     * 
     * @return all T entries without duplicated entries.
     */
    List<T> getAllDistinct();

    /**
     * Removes the T entity reference by the given id.
     * 
     * @param entityId the id of the T to remove from the persistance.
     */
    void remove( PK entityId );

    /**
     * Saves the given T in the persistance and returns it.
     * 
     * @param entity the T to save.
     * @return the saved T.
     */
    T save( T entity );

}
